This Getting Started Guide provides the following information to help you get started using the eBay .NET SDK:
The eBay .NET SDK is a set of libraries and tools intended to simplify and speed up application development for .NET developers who want to create applications that access eBay through the eBay Trading API. The libraries provide convenience classes that do the heavy lifting for you in handling communication with the eBay platform, handling errors, logging, and so forth. The libraries also provide a wrapper layer for the Trading API calls, providing simplified access to request and response fields and eliminating the need to handle XML.
The eBay Trading API is an extensive API enabling an application to do these and other types of activities on eBay:
The Trading API is documented thoroughly in the Trading API Guide and Call Reference , which you refer to when you write code that constructs and processes data from the API objects in the SDK. (The SDK documentation set does not provide any details on the Trading API.)
The following screen capture shows the typical directory structure of the SDK after installation:
The following table provides a brief description for the main items of interest in the SDK distribution:
| Directory/File | Description |
|---|---|
| Doc | Directory containing this guide, tutorials, the SDK library reference, and release notes. |
| Misc | Directory containing the EULA, application icon, links to the eBay Windows Development Center, etc. |
| Samples | Directory containing C# and VB.Net samples. |
| Source | Directory containing source for the SDK lib, the attributes, lib, the samples helper lib, and the sanity test lib. You do not need to customize any source code unless you want to upgrade to a newer Trading API WSDL that is supported by the current version of the SDK lib. If you wish to do such an upgrade, you need to generate the new proxy class (code stubs) from the new WSDL first using the Code Generator and then write wrapper code for the new or changed elements from the new WSDL, prior to rebuilding the SDK lib from the source. |
| Tools | Directory containing the code generator source and batch files. These are not needed unless you want to upgrade to a newer Trading API WSDL than is supported by the current SDK lib. These tools generate the proxy class (code stubs) from the new WSDL and also add certain customizations, such as using collection instead of array for container type, adding SOAP extension for logging purpose, and other eBay specific fixes. |
| wsdl | Directory containing the WSDL used in this version of the SDK. |
| eBay.build | A NAnt build script supporting .NET 2.0 and VS2005 builds. |
| eBay.Service.dll | The redistributable SDK lib. Must be distributed with every eBay .NET SDK program. If you customize the source, you would replace this with the customized lib, but retaining the same name. |
| eBay.Service.SDK.Attribute.dll | An optional redistributable attributes lib. This is only required if your program uses the eBay Attributes API. |
| SamplesHelper.dll | Used only for the samples. |
| eBaySDKLicense | The common development and distribution license you are subject to. |
Before Using the the SDK you will need the following:
When you deploy your program, the target computer requires:
The eBay SDKs can be downloaded from the eBay Windows developer center. The SDK is released at regular intervals to support the newer Trading API WSDL versions, although the WSDL version supported by SDK lags the latest version that is available.
The WSDLs can be downloaded from https://developer.ebay.com/webservices/Version/ebaySvc.wsdl, where Version is replaced by the version number of the WSDL release to be downloaded, for example, https://developer.ebay.com/webservices/687/ebaySvc.wsdl.
The latest released WSDL version can always be found at https://developer.ebay.com/webservices/latest/ebaySvc.wsdl.
To install the eBay .NET SDK,
The following diagram illustrates the overall architecture of the eBay .NET SDK:
As shown in the illustration, the SDK kernel handles the SOAP communication with eBay for the application, using ApiCall properties. The application uses Api call wrappers to build the Trading API requests and the SDK kernel sends the corresponding SOAP request to the eBay Trading API. The response from the Trading API is handled by the SDK kernel, which wraps the response into the appropriate call wrapper response. The application can then extract data as needed from the response object.
Notice that the illustration shows two paths from the ApiCall layer to the Request and Response objects that are accessed by the application. This indicates that although the call wrappers may be used, you may optionally bypass the call wrappers in order to allow the application to access the underlying SOAP requests and responses if necessary.
The following diagram shows a bit more of the underlying classes used in the SDK kernel-to-Trading API communication:
As shown, the ApiCall base class has an ApiContext property that contains the key information required for accessing the eBay Trading API. The ApiContext class is a singleton that is shared by all call wrapper instances in the same session (each call wrapper is an extension of ApiCall.) The critical properties of ApiContext are shown above:
The following diagram shows a bit more of the underlying classes used in the SDK kernel-to-Trading API communication:
As shown, the ApiCall base class is extended by each of the Api call wrapper classes, each of which corresponds to an equivalent call in the Trading API. Notice that each wrapper class instance in your code shares the same ApiContext object, which is set with valid URL, token, and site values.
In order to build the call request, refer to the Trading API call that the SDK call is based on. The SDK call is identical to its Trading API equivalent, except that the SDK version of the call has Call appended to it. For example, AddItem in the Trading API becomes AddItemCall in the SDK.
Some of the properties of the call wrapper object are used for input, some for output. To determine this for a particular call and to learn more about constructing any input objects required by a call wrapper, refer to the Trading API Call Reference section on input fields for detailed information.
The actual data returned in each call response can vary depending on the data supplied in the call request. Refer to the Trading API Call Reference sections on output fields for details on the possible data that could be returned for each call.
The following diagram shows the two main core SDK classes ApiCall and ApiContext, along with some API call wrapper classes that extend ApiCall:
The ApiCall base class is not used directly, but is shown here because all the call wrapper classes extend it. Some of the more commonly used properties of the ApiCall base class are also shown. These are properties you would set on a per-call basis.
The ApiContext class is a singleton containing properties you set to be in effect for all calls in the current session. The ApiCredential and SoapApiServerUrl properties are required, the others are available should you want to use them.
| Class/Property Name | Description |
|---|---|
| ApiContext | Provides data required by the call wrapper classes (which are based on ApiCall) in order to communicate with eBay, such as tokens, URLs, and so forth. It also provides properties needed for logging, call retries, call metrics. See ApiContext for more information. |
| ApiException | Contains any exceptions that resulted from the API call. |
| CallMetricsEntry | Holds the optional call metrics object used to track performance of this call. |
| CallRetry | Specifies the call retry that is to occur for this call if the exception specified in the CallRetry object is encountered. |
| EnableCompression | Boolean for specifying whether the response data from this call should be compressed at the server to reduce transfer size. |
| HasError | Boolean indicating whether the call response contains an error. |
| HasWarning | Boolean indicating whether the call response contains a warning. |
| Class/Property Name | Description |
|---|---|
| ApiCredential | Used to hold the token that authorizes the application to access eBay on behalf of the user. |
| ApiLogManager | Used to contain the various logger objects used to implement logging in your application. |
| CallMetricsTable | Table used to hold metrics logging information during the application calls to eBay. |
| EnableMetrics | Boolean turning on or off the logging of performance data during calls to the eBay platform. |
| EPSServerUrl | Used to hold the URL to use for uploading pictures to eBay Picture Service |
| ErrorLanguage | Used to specify the use of a language other than the one used on the site you are accessing in any returned error messages. |
| LastCallTime | Holds the time of the last API call. |
| Site | Used to specify the eBay site that the application is accessing. |
| SoapApiServerUrl | Specifies the URL indicating the eBay server and endpoint used by the Trading API: the call requests are sent to this URL. |
Most Trading API calls you make from the .NET SDK require an authorization token, which represents the user's authorization of your application to access eBay on behalf of that user. If eBay authorization tokens are new to you, review the short and focused topic Getting Tokens in the Trading API Guide. Be especially attentive to the different requirements of single-user and multi-user applications. There is also a very handy Getting Tokens tutorial.
Be aware that the methodology used in the .NET SDK sample applications to get and store the token is for a single-user application, for example, an in-house application that you use to do your own batch listings, where you can get the token in advance. In this scenario, you provide a token at design time within the App.config file; at runtime the sample programs load that stored value into the ApiCredential property of the ApiContext class instance.
However, multi-user applications (ones that you make available to other users not known in advance) would use a different method of obtaining and storing the token. Such applications would subsequently retrieve that token at runtime and load it into the ApiCredential property of the ApiContext class. For multi-user applications, you need to follow the instructions provided in Configuring the Consent Flow for Applications with Multiple Users . You also need to follow the process described in Getting Tokens for Applications with Multiple Users.
The follow .NET sample programs may be useful to you:
The samples will not run unless you add a valid auth token(user token) to the samples and rebuild them.
To build the samples,
locate the App.config file for each project in the solution:
Locate the line adding a key containing ApiToken in the name, and for the value, insert the Auth token (user token) for a user that you created in the sandbox as described earlier under Requirements.
As shown here:
All .NET SDK applications communicate with an eBay site following the same basic procedure.
For details, see Making an SDK Call.
The following are advanced topics on commonly used SDK features:
The eBay API architecture uses metadata to describe rules for listing items and managing them through the life cycle of a sale. An example of metadata are the item categories for a given site, which is obtained by a call to GetCategory. This metadata typically is too large to retrieve every time you need it. Instead, you should cache that data locally and update it incrementally as needed. Your application can update the cached metadata periodically, either on a regular schedule or when the API reports that metadata has changed.
For example, the GetCategory call returns a version number for the current category hierarchy, and can be used to detect when this version number has changed. For more information about the category hierarchy version number see Maintaining Category Data in the eBay Trading API Guide.
The SDK provides the ability to log your application's SDK activities (It doesn't support special logging that you want to emit from your application's own, non-SDK related operations.) The type of information logged depends on how you initialize the logger object. For example, you can set the logger to log informational messages, exceptions, and/or the payload of the API call requests and responses. For debugging purposes, you would log all three of those message types. For a deployed application you might want to log only exceptions.
To add logging to your application, you instantiate an instance of the ApiLogManager class in your ApiContext object. You then add a FileLogger instance to the ApiLogManager, specifying the name of the log file and setting the logging booleans to the type of logging you want in the FileLogger constructor. The following snippet from the sample program ConsoleAddFixedPriceItem (located in /Samples/C#/ConsoleAddFixedPriceItem) shows how logging is added:
apiContext = new ApiContext();
//set Api logging
apiContext.ApiLogManager = new ApiLogManager();
apiContext.ApiLogManager.ApiLoggerList.Add(new FileLogger("listing_log.txt", true, true, true)
apiContext.ApiLogManager.EnableLogging = true;
// set other api context properties...
where the name of the log file is specified as listing_log.txt, and the logger is set to log everying. In the FileLogger constructor, the first boolean controls information logging, the second boolean controls the ApiMessage payload logging, and the third boolean controls exception logging. You can turn these on or off in any combination you wish. You can also change these properties at runtime if you wish.
For more information and useful tips on logging, see Logging Best Practices.
During development, you may wish to log performance data for specific calls, in order to determine application performance before you deploy your application. The call metrics feature allows you to do this. This feature is intended for development, not for deployed applications.
For more information and code samples on using call metrics logging, see Enabling Call Metrics Logging.
The SDK provides three classes for exceptions:
You can catch these exceptions and handle them as desired. One way to make use of these exceptions is to use a CallRetry object to retry the call for exceptions resulting from network problems or a busy server.
When your application accesses the eBay platform using the SDK, errors can occur, such as network connection errors, an eBay server that is busy and fails to respond to the call request quickly enough, or some failure in the SDK layer itself. For many types of these failures, your application should retry the call. For example, for most calls that fail due to HTTP problems, such as error 502 bad gateway, error 404, and so forth, you should retry two or three times. Similarly, API call failures, notably AddItem, can occur even though the request is validly constructed due to server traffic; so you should retry the call for those failures also.
The SDK provides an easy way to make call retries using the ApiCall class property named CallRetry. All that you need to do is to instantiate an object of the CallRetry class and set the number of retries, the errors for which you want to retry and the interval at which you want to retry.
Retry only for errors caused on the eBay server side and not because of an error in your application, because retries will not help resolve application errors. You should normally try no more than 2 times. You should check the Error result set returned by the API call and set valid input arguments before you retry. (An easy way to figure out what is causing the error is to open the log and inspect the call request and response.)
You can retry on any of following errors:
For details and a complete code sample, see the knowledgebase article How can I retry a call with the .NET SDK?
The SDK is thread-safe and supports multithreading. However, your application is limited in the number of simultaneous call threads it can use to access the eBay platform through the API. For details on these and other limits, see the application compatiblity check page.
By default, the HTTP client of .Net framework does not allow more than 2 HTTP connections with any server. If your applcation uses multi-threads to call eBay servers, you may want to change the HTTP connection limit for better performance.
You can do this in either of the following two ways:
<system.net> <connectionManagement> <add address="*" maxconnection="5"/> </connectionManagement> </system.net>
ServicePointManager.DefaultConnectionLimit = 5;
Either of the above methods can be used to change the allowed connections to 5.
For sample code, see the Multithreading sample located in the SDK subdirectory /Samples/C#/MultiThread.
You might notice that date-time values returned from eBay may appear to be different from the time stamps you see on the eBay.com Web site and the Sandbox Web site. The reasons for this is that times are displayed in the local timezone for that site (with the US site using Pacific Time) while the time stamps returned by the API are in GMT (UTC). For more details, refer to Time Valuesin the API documentation.
For example, the following scenario can occur with an application based on the SDK: suppose that your application makes a request using the local time (for example, 10 AM Pacific Time). That time in the request is changed by the Trading API to GMT (for example, to 5 PM GMT). And a GMT time returned from the Trading API (for example, 1 PM) received by an application is converted by the SDK to local time (for example, to 6 AM).
Some classes provide the ability to specify whether to use local or GMT time. For example, if are using the TimeFilter class, it has properties that allow you to set the time specifically in GMT: TimeFilter.TimeFromUTC and TimeFilter.TimeToUTC. For more information, see the topic for this class in the Library Reference located at the SDK install subdirectory \docs\LibRef. (The TimeFilter class properties TimeFilter.TimeFrom and TimeFilter.TimeTo specify local computer time.)
Additional information is available in the following two MSDN Library topics:
In some cases you might want to access new or changed fields (in an existing API call) that are available in a more recent WSDL version than is supported by the current SDK's API call wrapper classes. To do this, you need to "bypass" the call wrapper class and write your own code that writes data to the new fields and processes the new data returned in the call response. You do this by calling ExecuteRequest instead of Execute, which uses the underlying SOAP request object that you populate using your own code. The response is returned to the underlying SOAP response object, from which you can extract the data using your own code rather than the call wrapper convenience layer.
Notice that if you do use ExecuteRequest directly to call the eBay API, then you need to explicitly cast the response to the proper type, as shown in this code snippet:
GetSellerTransactionsCall gst = new GetSellerTransactionsCall(this.apiContext); GetSellerTransactionsRequestType req = new GetSellerTransactionsRequestType(); GetSellerTransactionsResponseType resp = (GetSellerTransactionsResponseType)gst.ExecuteRequest(req);
For more details, see How to "Bypass" the Call Wrappers to Execute API Calls.
The ApiCall class used to execute requests to the eBay API has HTTP compression turned on by default. This greatly reduces the size of response data from the API. HTTP compression is especially advantageous for calls such as GetCategories that return large amounts of data. If you need to turn HTTP compression off (or back on), use the EnableCompression property of the ApiCall class.
The SDK is compiled to support a specific version of the Trading API WSDL. In most cases, you do not need to update the SDK to a newer Trading API version, because the SDK is released at regular intervals to provide support for newer API versions. (Typically, the SDK lags the current Trading API by a few versions.) However, if you need you need access to some new features supported by a newer WSDL, you can update the SDK to a newer WSDL yourself. Updating the SDK to a new WSDL requires you to rebuild the SDK Kernel and generate code stubs.
| Note: The SDK update and rebuild process described here is not recommended for most SDK users. Only advanced developers with significant experience using the eBay trading API should undertake this. |
The SDK kernel (eBay.Service.dll)is already built in each SDK release: it is ready for use and redistribution as needed. You only need to rebuild it if you wish to update the kernel to a newer WSDL version.
Each version of the eBay .NET SDK is based on a specific version of the Trading API WSDL. This WSDL is updated by eBay on a regular basis to provide new or enhanced features. However, because the SDK is updated less frequently than the Trading API WSDL, the SDK tends to lag the latest WSDL. This means that new features available only in the latest WSDL might not be available in the latest SDK.
To get around this, you can update the SDK kernel to the latest WSDL using this general process:
In most cases, you should not use the Sanity Test suite to test your work. However, if you do need to use Sanity Test, you need to first install NUnit (version 2.4.7, "net-2.0"), which can be obtained from the You can find tutorials, code samples, and knowledgebase article links at the Samples/Tutorials page. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement. © 2009–2010 eBay Inc. All rights reserved.
Other Links and Resources
Note that this version of the eBay SDK for .NET can be built using either Microsoft
Visual Studio 2005 (.NET Framework 2.0) or Microsoft Visual Studio 2008 (.NET Framework
2.0/3.0/3.5). You may see a conversion dialog if you are using Microsoft Visual
Studio 2008, because this version of the eBay SDK was built using Microsoft
Visual Studio 2005. Choose, "Finish" when you see the conversion dialog.
eBay and the eBay logo are registered trademarks of eBay Inc.
All other brands are the property of their respective owners.